package my.collections;

/**
 * The Stack class represents a last-in-first-out (LIFO) stack of objects.
 * And this class can look at the object which has the highest(or lowest or so) value.
 * So every object onto the stack must be comparable to each other. 
 * @param <E>
 */
public interface IStackForPriorExamination <E extends Comparable<E>>{
	/**
	 * Pushes an item onto the top of this stack.
	 * If the Element e is null, throws NullPointerException.
	 * @param e
	 * @throws NullPointerException
	 */
	public void push(E e);
	
	/**
	 * Removes the object at the top of this stack and returns that object as the value of this function.
	 * If the stack is empty, throws java.util.EmptyStackException.
	 * @return
	 * @throws java.util.EmptyStackException
	 */
	public E pop();
	
	/**
	 * Looks at the object which has the median value among the all objects without removing it from the stack.
	 * Returns the object which has the value of <code>((size()/2 + 1)</code>th lowest.
	 * <pre>
	 * e.g.
	 *  When the stack has the following values (2, 1, 2, 2, 6, 4, 2, 5)
	 *  this method returns 2 and doesn't remove that object.
	 *  
	 *  When the stack has the following values (7, 1, 3, 3, 5, 1, 2, 4, 3)
	 *  this method returns 3 and doesn't remove that object.
	 * </pre>
	 * If the stack is empty, throws java.util.EmptyStackException.
	 * @return
	 * @throws java.util.EmptyStackException
	 */
	public E peekMedian();
	
	/**
	 * Looks at the object which has the maximum value among the all objects without removing it from the stack.
	 * <pre>
	 * e.g.
	 *  When the stack has the following values (2, 1, 2, 2, 6, 4, 2, 5)
	 *  this method returns 6 and doesn't remove that object.
	 *  
	 *  When the stack has the following values (7, 1, 3, 3, 5, 1, 2, 4, 3)
	 *  this method returns 7 and doesn't remove that object.
	 * </pre>
	 * If the stack is empty, throws java.util.EmptyStackException.
	 * @return
	 * @throws java.util.EmptyStackException
	 */
	public E peekMaximum();
	
	/**
	 * Looks at the object which has the minimum value among the all objects without removing it from the stack.
	 * <pre>
	 * e.g.
	 *  When the stack has the following values (2, 1, 2, 2, 6, 4, 2, 5)
	 *  this method returns 1 and doesn't remove that object.
	 *  
	 *  When the stack has the following values (7, 1, 3, 3, 5, 1, 2, 4, 3)
	 *  this method returns 1 and doesn't remove that object.
	 * </pre>
	 * If the stack is empty, throws java.util.EmptyStackException.
	 * @return
	 * @throws java.util.EmptyStackException
	 */	
	public E peekMinimum();
	
	/**
	 * Returns the number of objects in this stack
	 * @return
	 */
	public int size();
}
